/*
 * Copyright 2002-2019 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.transaction;

import java.io.Flushable;

/**
 * Representation of the status of a transaction.
 *
 * <p>Transactional code can use this to retrieve status information,
 * and to programmatically request a rollback (instead of throwing
 * an exception that causes an implicit rollback).
 *
 * <p>Includes the {@link SavepointManager} interface to provide access
 * to savepoint management facilities. Note that savepoint management
 * is only available if supported by the underlying transaction manager.
 *
 * @author Juergen Hoeller
 * @since 27.03.2003
 * @see #setRollbackOnly()
 * @see PlatformTransactionManager#getTransaction
 * @see org.springframework.transaction.support.TransactionCallback#doInTransaction
 * @see org.springframework.transaction.interceptor.TransactionInterceptor#currentTransactionStatus()
 */
/*
1. 总结
TransactionStatus 是Spring事务框架中表示事务状态的接口
它继承了 TransactionExecution、SavepointManager 和 Flushable 接口
提供了事务状态查询和控制功能，是编程式事务管理的核心组件
2. 内部成员说明
方法定义
	hasSavepoint(): 判断当前事务是否基于保存点创建（即是否为嵌套事务）
	flush(): 刷新底层会话到数据存储，如Hibernate/JPA会话
	isCompleted(): 判断事务是否已完成
	isNewTransaction(): 判断是否为新事务
	isRollbackOnly(): 判断事务是否已标记为回滚
	setRollbackOnly(): 标记事务为回滚状态
	createSavepoint(): 创建保存点
	rollbackToSavepoint(Object savepoint): 回滚到指定保存点
	releaseSavepoint(Object savepoint): 释放保存点
3. 类关系结构
TransactionStatus (interface)	事务状态的抽象表示，包含事务执行、保存点管理和刷新功能
  └──AbstractTransactionStatus (class)	抽象事务状态实现，提供了通用的事务状态管理逻辑
  	  ├── SimpleTransactionStatus (class)	简单的事务状态实现，适用于基本的事务场景
  	  └── DefaultTransactionStatus (class)	默认的事务状态实现，提供了完整的事务状态管理功能

与其他相关类的区别：
	TransactionStatus: 事务状态的抽象表示，包含事务执行、保存点管理和刷新功能
	TransactionExecution: 事务执行的接口，定义了事务生命周期的基本操作
	SavepointManager: 保存点管理接口，提供保存点的创建、回滚和释放功能
	Flushable: 可刷新接口，用于触发资源的刷新操作
4. 使用场景
	编程式事务管理中需要手动控制事务状态
	需要创建和管理保存点的复杂事务场景
	需要显式刷新底层会话的场景
	需要根据条件决定是否回滚事务的业务逻辑
	处理嵌套事务时需要判断事务类型
5. 实际代码应用示例
@Service
public class UserService {

    @Autowired
    private PlatformTransactionManager transactionManager;

    public void createUserWithCustomLogic(User user) {
        TransactionStatus status = transactionManager.getTransaction(new DefaultTransactionDefinition());
        try {
            // 执行业务逻辑
            if (user.getId() == null) {
                // 创建用户
                userRepository.save(user);

                // 显式刷新会话
                status.flush();

                // 创建保存点
                Object savepoint = status.createSavepoint();

                // 执行其他操作
                updateUserPreferences(user.getId(), "default");

                // 如果需要回滚到保存点
                if (someCondition()) {
                    status.rollbackToSavepoint(savepoint);
                    status.releaseSavepoint(savepoint);
                }
            }

            // 提交事务
            transactionManager.commit(status);
        } catch (Exception e) {
            // 标记事务为回滚
            status.setRollbackOnly();
            transactionManager.rollback(status);
            throw e;
        }
    }
}

 */
public interface TransactionStatus extends TransactionExecution, SavepointManager, Flushable {

	/**
	 * Return whether this transaction internally carries a savepoint,
	 * that is, has been created as nested transaction based on a savepoint.
	 * <p>This method is mainly here for diagnostic purposes, alongside
	 * {@link #isNewTransaction()}. For programmatic handling of custom
	 * savepoints, use the operations provided by {@link SavepointManager}.
	 * @see #isNewTransaction()
	 * @see #createSavepoint()
	 * @see #rollbackToSavepoint(Object)
	 * @see #releaseSavepoint(Object)
	 */
	boolean hasSavepoint();

	/**
	 * Flush the underlying session to the datastore, if applicable:
	 * for example, all affected Hibernate/JPA sessions.
	 * <p>This is effectively just a hint and may be a no-op if the underlying
	 * transaction manager does not have a flush concept. A flush signal may
	 * get applied to the primary resource or to transaction synchronizations,
	 * depending on the underlying resource.
	 */
	@Override
	void flush();

}
